/**
 * Copyright (c) 2013-2022 Nikita Koksharov
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.redisson.api;

import java.util.concurrent.TimeUnit;

/**
 * 限流器接口，用于控制访问速率。
 * 该接口扩展了RRateLimiterAsync和RExpirable，支持异步操作和过期时间设置。
 * 提供了设置和获取限流速率、尝试和强制获取许可的方法，以及查询可用许可数量和配置信息的方法。
 */
public interface RRateLimiter extends RRateLimiterAsync, RExpirable {

    /**
     * 尝试设置限流模式和速率。
     *
     * @param mode 限流模式，如请求速率或并发数。
     * @param rate 速率值，取决于限流模式。
     * @param rateInterval 速率计算的时间间隔。
     * @param rateIntervalUnit 时间间隔的单位。
     * @return 如果设置成功返回true，否则返回false。
     */
    boolean trySetRate(RateType mode, long rate, long rateInterval, RateIntervalUnit rateIntervalUnit);

    /**
     * 设置限流模式和速率。
     *
     * @param mode 限流模式，如请求速率或并发数。
     * @param rate 速率值，取决于限流模式。
     * @param rateInterval 速率计算的时间间隔。
     * @param rateIntervalUnit 时间间隔的单位。
     */
    void setRate(RateType mode, long rate, long rateInterval, RateIntervalUnit rateIntervalUnit);

    /**
     * 尝试立即获取一个许可。
     *
     * @return 如果许可可用则返回true，否则返回false。
     */
    boolean tryAcquire();

    /**
     * 尝试立即获取指定数量的许可。
     *
     * @param permits 要获取的许可数量。
     * @return 如果许可可用则返回true，否则返回false。
     */
    boolean tryAcquire(long permits);

    /**
     * 强制获取一个许可，如果立即不可用则等待。
     */
    void acquire();

    /**
     * 强制获取指定数量的许可，如果立即不可用则等待。
     *
     * @param permits 要获取的许可数量。
     */
    void acquire(long permits);

    /**
     * 尝试在指定时间内获取一个许可。
     *
     * @param timeout 等待许可的超时时间。
     * @param unit 超时时间的单位。
     * @return 如果许可获取成功则返回true，否则返回false。
     */
    boolean tryAcquire(long timeout, TimeUnit unit);

    /**
     * 尝试在指定时间内获取指定数量的许可。
     *
     * @param permits 要获取的许可数量。
     * @param timeout 等待许可的超时时间。
     * @param unit 超时时间的单位。
     * @return 如果许可获取成功则返回true，否则返回false。
     */
    boolean tryAcquire(long permits, long timeout, TimeUnit unit);

    /**
     * 获取当前限流器的配置信息。
     *
     * @return 限流器的配置信息对象。
     */
    RateLimiterConfig getConfig();

    /**
     * 获取当前可用的许可数量。
     *
     * @return 可用的许可数量。
     */
    long availablePermits();
}
